Příklad z praxe - definovatelná agenda Reklamace

Ostatní návody ze skupiny o definovatelných objektech (viz seznam na konci stránky) popisují jednotlivé obecné mechanismy odděleně - jak založit business objekt, jak přidat položku, jak udělat tiskovou sestavu apod. Tento návod je oproti tomu jeden souvislý, konkrétní příběh od úplného začátku až po nasazení do produkce a úklid: dokladová agenda Reklamace, na které si ukážeme prakticky všechny důležité možnosti definovatelných business objektů pohromadě. Používejte jej jako referenční scénář - jednotlivé kroky odkazují na obecné návody, kde najdete detailní vysvětlení dané dílčí techniky.

Cíl příkladu

Vytvoříme dokladovou agendu Reklamace:

  • na hlavičce dokladu se zadává firma (to je u dokladového business objektu k dispozici automaticky, viz krok 1) a osoba - vlastní položka s odkazem do číselníku, na které si ukážeme obecnou techniku tvorby referenčních položek s cizím klíčem,
  • vedle toho založíme i samostatný definovatelný číselníkový objekt Typy reklamací, který demonstruje, že business objekty lze kombinovat,
  • řádky mohou být trojího druhu - volný text, text doplněný počtem, nebo skladová karta se skladem a počtem - podle toho, jaký typ řádku si uživatel zvolí (mechanismus "Seznam layoutů pro multigrid"),
  • nad agendou existuje vlastní tisková sestava, která u řádku se skladovou kartou navíc zobrazí aktuální stav dané karty na všech skladech,
  • celé řešení lze přenést z testovacího prostředí do produkce přes instalační sadu,
  • a nakonec si ukážeme, jak systém brání nekonzistentnímu smazání souvisejících definic.
1. Hlavičkový business objekt Reklamace

Podle kapitoly Vytvoření definovatelného business objektu založte v agendě Definice business objektů nový objekt:

  • Typ: Doklad
  • Interní název třídy: Complaint
  • Zobrazovaný název: Reklamace
  • Název tabulky a API endpoint se předvyplní automaticky podle názvu třídy - ponechte je. Protože je Název třídy anglický, výsledek dává smysl i jazykově: hodnota názvu tabulky Complaints, hodnota API endpointu complaints (viz vysvětlení principu v kapitole Vytvoření definovatelného business objektu).

Do definice názvy zadáváte bez prefixů. Výsledná třída je DefBO_Complaint, tabulka ET$Complaints a endpoint pro data defbo_complaints. U číselníku Typy reklamací bude úplný název třídy DefBO_ComplaintType. Pravidla shrnuje kapitola Technické názvy a prefixy.

Definici uložte a poznamenejte si vygenerované CLSID - budete jej potřebovat v dalších krocích.

Dokladový business objekt obsahuje standardní pole Firma a samostatnou záložku Firma. Tyto údaje není potřeba přidávat jako vlastní položky.

2. Definovatelný číselník Typy reklamací

Ukážeme si, že business objekty lze kombinovat - vedle dokladu vytvoříme ještě samostatný definovatelný číselníkový business objekt:

  • Typ: Číselníkový objekt
  • Interní název třídy: ComplaintType
  • Zobrazovaný název: Typ reklamace

Uložte a podle kapitoly Vytvoření definovatelné agendy nad ním rovnou vytvořte i jednoduchou číselníkovou agendu Typy reklamací. Po obnovení nabídky agend (viz krok 5) do ní naplňte několik základních záznamů, např. Vada zboží, Nedodání, Jiné.

Číselník Typy reklamací zde slouží jako samostatná evidence. Po vytvoření jeho agendy typu Číselník jej můžete použít také jako cíl odkazové položky s cizím klíčem. Postup a podmínky registrace popisuje doplnění vlastních položek.

3. Vlastní položka hlavičky s odkazem do číselníku (Osoba)

Podle kapitoly Doplnění vlastních položek doplňte na objekt Complaint položku s odkazem do číselníku osob - na tomto konkrétním případě je vidět obecná technika, kterou použijete pro odkaz do jakéhokoli systémového číselníku:

  1. V editoru položky zadejte Název položky: PERSON - technický název pište anglicky, stejně jako u business objektu v kroku 1.
  2. Popis a Popisek položky naopak zadejte česky: Osoba. Tyto texty totiž vidí přímo uživatelé v aplikaci.
  3. Datový typ nastavte na Identifikátor - ne na Znaky! Právě datový typ Identifikátor je jediný, u kterého se v poli Způsob editace vůbec nabídne volba Číselník - u datového typu Znaky je k dispozici jen Adresářová cesta a Volby, žádný číselník. (Sloupec "Databázový typ" v přehledu položek pak u takové položky nadále ukazuje "Identifikátor", zatímco obecný "Datový typ" v API se stále jmenuje podle staršího názvosloví "Znaky" - jde o dva různé, historicky oddělené popisy typu položky v ABRA Gen, nenechte se zmást tím, že oba používají podobná slova pro různé věci.)
  4. Způsob editace nastavte na Číselník - zadání hodnot(y).
  5. Do pole Číselník zadejte přesně Číselník osob. Toto pole nefiltruje našeptáváním podle části textu - buď zadáte přesný název číselníku (Popisek), a systém jej sám dosadí, nebo otevřete rozbalovací seznam (Alt+šipka dolů) a v abecedně řazeném seznamu (řazeném podle znaku, ne podle české abecedy - takže "Č" je hned za "C", ne až za "Z") jej najdete ručně. Nepřesný nebo částečný text se může tiše navázat na jiný, podobně pojmenovaný číselník (např. zadání "firmy" se místo číselníku firem napojí na první číselník, který slovo "firmy" obsahuje kdekoli v názvu) - po zadání si proto vždy zkontrolujte, že se v poli Číselník zobrazuje přesně očekávaný název.
  6. Zatrhněte Extra a poté Cizí klíč (viditelné a zaškrtnutelné až pro datový typ Identifikátor se způsobem editace Číselník) - v tomto pořadí, protože jakmile je Cizí klíč jednou uložený, pole Číselník se uzamkne a nejde už dodatečně změnit ani opravit (zkusíte-li to, systém nahlásí, že položku "Třída číselníku" nelze měnit). Pokud se spletete, položku smažte a založte znovu, oprava už nejde.

Po uložení systém automaticky přejmenuje položku na X_PERSON_ID - u datového typu Identifikátor se za název položky vždy automaticky přidá přípona _ID, navíc k obvyklé předponě X_ pro Extra položky.

Dokladový business objekt obsahuje standardní pole Firma. Pro tento příklad proto vlastní odkaz na firmu nezakládejte. Při vytváření jiné odkazové položky vyberte odpovídající registrovaný číselník podle obecného postupu.

4. Řádkový objekt se třemi typy řádků

Podle kapitoly Vytvoření řádkového objektu založte objekt typu Řádek s Názvem třídy ComplaintLine, Popiskem Řádky reklamace, Třídou hlavičky nastavenou na Complaint a zatrženou volbou Kolekce řádků (hlavní kolekce).

Řádky reklamace mají být trojího druhu - typ 1 (Text) pro volnou textovou poznámku, typ 2 (Text s počtem) pro poznámku doplněnou množstvím, a typ 3 (Skladová karta) pro konkrétní reklamovanou položku se skladem a počtem. Na řádkový objekt doplňte tyto vlastní položky (u všech zatrhněte Extra a pište technický Název anglicky, Popis/Popisek naopak česky - viz krok 3):

4a. Rozhodná položka ROWTYPE

  1. Založte položku ROWTYPE (Popisek Typ řádku) s Datovým typem Celé číslo a Způsobem editace Skrytý seznam (combo box) - volbu Seznam layoutů pro multigrid lze zatrhnout až u položky typu Celé číslo se způsobem editace Skrytý seznam, Svislý přepínač nebo Vodorovný přepínač; u výchozího způsobu editace (Výchozí) zůstane needitovatelná. Teprve po nastavení Skrytého seznamu ji zatrhněte - tato položka se tak stane rozhodnou položkou pro layout multigridu (v definici položek jedné třídy business objektu lze mít takto označenou jen jednu položku).
  2. Do pole Počítat od zadejte 1 - tím určíte, že první řádek seznamu voleb bude odpovídat hodnotě 1, ne výchozí 0.
  3. Do pole Volby (víceřádkové pole, technicky vlastnost Enumeration) zadejte na tři samostatné řádky:
    1. Text
    2. Text s počtem
    3. Skladová karta

Zatržení volby Seznam layoutů pro multigrid je pro fungování celého mechanismu nezbytné - bez něj se položka ROWTYPE uloží bez chyby a navenek se tváří jako běžné celé číslo, ale multigrid podle její hodnoty layout nepřepne, aniž by na to cokoli upozornilo. Nezapomeňte tento poslední dílčí krok provést - je dostupný, teprve když už je nastaven Způsob editace na Skrytý seznam (nebo přepínač), takže na něj lze snadno zapomenout.

Systém přiřazuje popisky jednotlivým hodnotám podle pořadí řádků v poli Volby, počínaje hodnotou z pole Počítat od (1. řádek = hodnota 1, 2. řádek = hodnota 2, 3. řádek = hodnota 3) - nejde o dvojice "popisek=hodnota", které byste zadávali sami. Pokud by bylo potřeba mezi hodnotami udělat mezeru (přeskočit některou hodnotu), stačí na její místo vložit v poli Volby prázdný řádek jako zástupný symbol - v tomto konkrétním příkladu to ale potřeba není, protože všechny tři typy řádku navazují na hodnoty 1, 2 a 3 bez mezery.

4b. Položky pro jednotlivé typy řádku

  • TEXT (Popisek Text) - Datový typ Znaky - pole Datový typ není při založení položky předvyplněné, hodnotu je nutné vždy vybrat explicitně (jinak systém při uložení nahlásí "Položka 'Datový typ' není nastavena."). Použije se u řádků typu 1 (Text) a typu 2 (Text s počtem).
  • QUANTITY (Popisek Počet) - Datový typ Celé číslo - použije se u řádků typu 2 (Text s počtem) a typu 3 (Skladová karta).
  • STORE (Popisek Sklad) - Datový typ Identifikátor, Způsob editace Číselník - zadání hodnot(y), Číselník = Číselník skladů, s cizím klíčem - postup zadání stejný jako u položky PERSON v kroku 3. Použije se u řádků typu 3 (Skladová karta).
  • STORECARD (Popisek Skladová karta) - Datový typ Identifikátor, Způsob editace Číselník - zadání hodnot(y), Číselník = Číselník skladových karet, s cizím klíčem - postup zadání stejný jako u položky PERSON v kroku 3. Použije se u řádků typu 3 (Skladová karta).

4c. Příprava layoutů v editoru rozložení sloupců

Přípravu rozložení proveďte až po vytvoření agendy, řady dokladů a nastavení práv v kroku 5. Poté se vraťte sem a připravte rozložení pro všechny tři typy řádků.

Nově založená kolekce řádků se na záložce Obsah agendy zobrazí zcela bez sloupců, dokud jí layout ručně nepřipravíte - obecný postup popisuje návod Editor rozložení sloupců multigridu, zde je konkrétní postup pro všechny tři typy řádku reklamace. Editor rozložení sloupců vždy pracuje s layoutem, který odpovídá aktuálně vybranému/otevřenému řádku v mřížce (dialog to potvrzuje popiskem "Aktivní pro aktuální data") - proto je potřeba mít pro každý typ řádku napřed alespoň jeden skutečný řádek s danou hodnotou položky Typ řádku:

  1. V agendě Reklamace založte nebo otevřete zkušební záznam a na záložce Obsah přidejte nový řádek (funkce Přidat). Do pole Typ řádku vyberte hodnotu Text a řádek uložte.
  2. Klikněte pravým tlačítkem myši na mřížku řádků a zvolte Editor rozložení sloupců. Vypněte Editovat společně, aby další úpravy platily pouze pro zvolený typ řádku. Dialog by měl ukazovat Rozložení: 1 (odpovídá právě přidanému řádku typu Text).
  3. Klikněte pravým tlačítkem myši do plochy editoru a zvolte Přidat sloupec. V otevřeném stromu položek řádkového objektu Řádky reklamace zatrhněte položku TEXT a potvrďte OK.
  4. V hlavním dialogu potvrďte tlačítkem OK a na dotaz, zda chcete uložit změnu (projeví se u ostatních uživatelů při dalším načtení rozložení sloupců), odpovězte Ano. Tím vznikne Globální rozložení sloupců pro hodnotu 1, platné pro všechny uživatele agendy.
  5. Přidejte druhý řádek, tentokrát s hodnotou Typ řádku Text s počtem, a řádek uložte. Znovu otevřete Editor rozložení sloupců - tentokrát by měl ukazovat Rozložení: 2. Stejným postupem přidejte položky TEXT a QUANTITY a uložte (OK → Ano).
  6. Přidejte třetí řádek s hodnotou Typ řádku Skladová karta, a řádek uložte. Znovu otevřete Editor rozložení sloupců - tentokrát by měl ukazovat Rozložení: 3. Přidejte postupně položky STORE, STORECARD a QUANTITY a uložte (OK → Ano).

Od této chvíle mřížka na záložce Obsah automaticky nabízí jiné sloupce podle toho, jakou hodnotu Typ řádku má právě otevřený/editovaný řádek - to je přesně mechanismus "Seznam layoutů pro multigrid", který měl podle zadání produktového vlastníka demonstrovat, že jeden řádkový objekt může mít podle rozhodné položky různé sloupcové rozložení.

5. Definice agendy Reklamace a obnovení nabídky

Podle kapitoly Vytvoření definovatelné agendy vytvořte nad objektem Complaint dokladovou agendu se Zobrazovaným názvem Reklamace. Jako Interní název můžete zadat Complaints; systém zaregistruje agendu jako DefSite_Complaints.

Po uložení definic znovu spusťte desktopového klienta, aby se obnovila nabídka agend. Při práci s již otevřenými formuláři a s API postupujte podle kapitoly Obnovení definic. Restart aplikačního serveru není obecně nutný po každém uložení definice.

Po novém přihlášení agendu Reklamace otevřete a ověřte seznam a detail včetně záložek Hlavička, Firma a Obsah. Konkrétní sloupce seznamu lze uživatelsky upravit.

Založte i odpovídající řadu dokladů a nastavte její ochranu jako chráněný objekt podle kapitoly Řada dokladů jako chráněný objekt, a nastavte práva k oběma novým agendám podle kapitoly První spuštění a kontrola agendy.

7. Zkušební záznam

Založte zkušební reklamaci - na hlavičce vyberte firmu (standardní pole) a osobu (naši vlastní položku), přidejte alespoň jeden textový řádek (typ 1), jeden textový řádek s počtem (typ 2) a jeden řádek se skladem, skladovou kartou a počtem (typ 3). Ověřte uložení, správné zobrazení sloupců podle typu řádku a funkčnost omezení a třídění.

8. Tisková sestava se stavy skladu

Podle návodu Tisková sestava nad definovatelnou agendou si nejprve uděláme základní sestavu průvodcem a poté ji rozšíříme o vlastní dataset se stavy zásob - konkrétní příklad použití obecného postupu z kapitoly Rozšíření o data mimo automaticky generovaný DynSQL.

8a. Základní sestava průvodcem

  1. V agendě Reklamace spusťte průvodce tiskovou sestavou přímo nad automaticky generovaným DynSQL - jako zdroj dat vyberte toto DynSQL a ve stromu polí přidejte položky z větve Main (hlavička) a z podřízené větve Rows (řádková kolekce).
  2. Dokončete průvodce. Výsledná sestava zvládne vytisknout hlavičku i všechny tři typy řádků (jejich společné i specifické sloupce), ale u řádků se skladovou kartou (typ 3) zatím nezobrazí nic navíc - to doplníme v dalším kroku.

8b. Rozšíření o stav skladových karet na jednotlivých skladech

U řádku se skladovou kartou (typ 3) chceme navíc zobrazit, kolik kusů dané karty je aktuálně na kterém skladu - tento údaj automaticky generované DynSQL neobsahuje, protože leží mimo agendu Reklamace. V systému jej ale najdeme v tabulce StoreSubCards ("dílčí skladové karty") - to je stejná tabulka, ze které čerpá stav zásob na skladech i standardní agenda Skladové karty. Její klíčová pole jsou StoreCard_ID (odkaz na skladovou kartu), Store_ID (odkaz na sklad) a Quantity (množství na daném skladu) - jeden řádek této tabulky odpovídá jedné kombinaci karta/sklad.

  1. Otevřete nástroj DynSQLEditor.exe a najděte automaticky generované DynSQL agendy Reklamace (v seznamu Dynamické SQL příkazy odpovídá registrovanému názvu agendy, v tomto příkladu DefSite_Complaints).
  2. Uložte si z něj vlastní upravitelnou kopii, napojenou na stejný programový bod. Na subzáložce Datasety uvidíte dva existující datasety - MAIN (hlavička, s automaticky přidanými joiny na řadu dokladů, firmu, období a uživatele) a ROWS (řádková kolekce, s polem Master nastaveným na MAIN a napevno napsanou podmínkou WHERE A.Parent_ID = :ID).
  3. V seznamu datasetů klikněte pravým tlačítkem myši a zvolte Nový - vznikne dataset s výchozí šablonou SELECT {FIELDS} FROM {WHERE}, kterou přepíšete. Vyplňte:
    • Název: STORESUBCARDS
    • Popiska: Stav skladové karty na skladech
    • Master: ROWS (do tohoto textového pole název datasetu napíšete ručně, nejde o výběr ze seznamu) - tím se nový dataset stane podřízeným datasetu s řádky.
    • SQL dotaz:
      SELECT {FIELDS} FROM StoreSubCards A {JOIN} WHERE A.StoreCard_ID = :X_STORECARD_ID {ANDWHERE}
  4. Na subzáložce Rozšířené fieldy tohoto nového datasetu (ne na subzáložce Aliasy - ta je pro JOIN na tabulky odpovídající existující business třídě, což tabulka stavů zásob není) doplňte dvě položky, každou s vlastním SQL výrazem: Store_ID (výraz A.Store_ID) a Quantity (výraz A.Quantity, popiska "Množství"). U položky Store_ID vyplňte i Packed CLSID business třídy skladu, abyste v sestavě mohli použít tečkovou notaci Store_ID.Code.

Šablony {FIELDS}, {JOIN} a {ANDWHERE} v SQL dotazu nejsou neúplná syntaxe - systém je při použití datasetu doplní sám (prázdné, pokud pro ně nic definováno není), stejně jako v obou automaticky generovaných datasetech MAIN a ROWS. Podmínku WHERE ... :X_STORECARD_ID je ale nutné napsat napevno vy sami, protože jde o povinnou vazbu na nadřízený dataset - stejně jako WHERE A.Parent_ID = :ID u datasetu ROWS. Parametr za dvojtečkou se automaticky naváže na stejnojmenné pole nadřízeného datasetu, zde tedy na technický název položky STORECARD (v databázi X_STORECARD_ID, viz krok 4b) - žádné další nastavení této vazby není potřeba.

U řádků typu 1 a 2, kde položka STORECARD není vyplněná, dotaz logicky nevrátí žádný řádek - v sestavě se tedy pod nimi žádný stav zásob nezobrazí.

  1. Dotaz uložte a v editoru tiskové sestavy nad touto vlastní kopií DynSQL přidejte vnořený pás (band) napojený na nový dataset STORESUBCARDS, umístěný pod pásem datasetu ROWS - obdobně jako je popsáno v kapitole Popis jednotlivých funkcí editoru pro vkládání vnořených dat.
  2. Do nového pásu vložte pole Quantity (množství) a pole identifikující sklad. Pokud jste u rozšířené položky Store_ID v předchozím kroku vyplnili Packed CLSID business třídy skladu, můžete konkrétní kód nebo název skladu zadat tečkovou notací přes ID, stejně jako je obecně popsáno v kapitole Dynamické SQL - subzáložka Datasety (tam na příkladu MAIN.Currency_ID.Code): zde tedy Store_ID.Code, případně Store_ID.Name. Bez vyplněného Packed CLSID budete mít k dispozici jen samotnou hodnotu identifikátoru skladu, bez možnosti se přes ni dostat k jeho kódu či názvu.

Výsledná sestava pak pro každou reklamaci vytiskne hlavičku, pod ní všechny řádky (s jejich sloupci podle typu) a u každého řádku se skladovou kartou navíc jeden dílčí řádek za každý sklad, na kterém se daná karta nachází, s jeho kódem a aktuálním množstvím.

9. Přenos do produkce

Až je celé řešení v testovacím prostředí hotové a ověřené, přeneste je podle návodu Přenos definovatelného řešení mezi spojeními pomocí instalační sady do produkčního spojení. Konkrétně pro tento příklad do instalační sady přidejte tyto položky (typy objektů v Průvodci přidáním položek, viz odkazovaný návod pro plné vysvětlení každého typu):

  • Definovatelné business objekty - všechny tři: Complaint, ComplaintType i ComplaintLine. Nezaměňte za typ Definovatelné číselníky - přestože ComplaintType má Typ Číselníkový objekt, jde stále o tentýž typ objektu instalační sady jako u ostatních dvou.
  • Definovatelné agendy - obě agendy: Reklamace i Typy reklamací. Průvodce by měl při jejich přidání sám nabídnout doplnění chybějících Definovatelných business objektů, na kterých jsou postaveny.
  • Definovatelné položky - všechny vlastní položky ze všech tří business objektů (PERSON, ROWTYPE, TEXT, QUANTITY, STORE, STORECARD).
  • Rozložení sloupců Editovatelného seznamu - globální rozložení kolekce vytvořené v kroku 4c včetně všech tří hodnot rozhodné položky ROWTYPE. Přidejte je ručně. Po importu ověřte volbu Seznam layoutů pro multigrid i zobrazení a přepínání všech tří rozložení podle pokynů k přenosu; případné chybějící nastavení doplňte v cílovém spojení.
  • Definovatelné DynSQL k definovatelným agendám - pouze pokud jste v kroku 8b vytvořili vlastní upravitelnou kopii DynSQL s datasetem STORESUBCARDS. Pokud jste zůstali jen u automaticky generovaného DynSQL a sestavy z kroku 8a, tento typ nepotřebujete. Místo instalační sady lze tuto konkrétní kopii DynSQL přenést i přímo z DynSQLEditor.exe (menu Export/Import → Definovatelné agendy → Exportovat, s připojením přímo na produkční spojení) - obě cesty jsou rovnocenné, viz Rozšíření o data mimo automaticky generovaný DynSQL. Tato přímá cesta ale přenáší jen samotné DynSQL - business objekty Complaint/ComplaintType/ComplaintLine a obě agendy musí být v produkčním spojení už vytvořené (instalační sadou nebo ručně), jinak se DynSQL nemá k čemu navázat.
  • Tiskové sestavy - vlastní tisková sestava z kroku 8.

Po přidání všech položek zkontrolujte hlášení o chybějících závislých objektech (mělo by se týkat jen business objektů, agend a DynSQL - u rozložení sloupců multigridu na něj nespoléhejte, viz odkazovaný návod), sadu exportujte a v produkčním spojení naimportujte. Po importu znovu restartujte aplikační server a ověřte, že reklamaci lze v produkčním prostředí založit, že multigrid u řádků nabízí stejné layouty podle typu řádku jako v testu, a že jde vytisknout stejná sestava se stavy skladu.

Řadu dokladů pro Reklamace (viz krok 5) instalační sada nepřenese - pro řady dokladů žádný typ objektu instalační sady neexistuje (obecné omezení, netýká se jen definovatelných business objektů). V produkčním spojení ji tedy musíte založit ručně znovu úplně stejným postupem jako v testu, včetně opětovného nastavení ochrany jako chráněného objektu - stejně jako práva k funkcím k oběma agendám.

10. Bezpečné rušení definic (validace závislostí)

Rušení definic provádějte pouze v testovací databázi se zálohou: odstranění definice business objektu odstraňuje také jeho tabulku a data. Závislosti a pořadí odstranění ověřte podle funkce Vymazat v agendě Definice business objektů. Validační kontroly nenahrazují kontrolu odkazů ve vlastních skriptech a výstupech.

Přehled použitých obecných návodů

Tento příklad kombinuje techniky popsané v následujících obecných návodech ze stejné skupiny: